  This file documents the installation and use of the programs in Web2c,
an implementation of Donald Knuth's TeX system.

  Copyright (C) 1996, 97 K. Berry & O. Weber.

  Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

  Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

  Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation

Web2c
*****

  This document describes how to install and use the programs in the
Web2c implementation of the TeX system, especially for Unix systems.  It
corresponds to Web2c version 7.3.1, released in May 1999.

Introduction
************

  This manual corresponds to version 7.3.1 of Web2c, released in
May 1999.

  "Web2c" is the name of a TeX implementation, originally for Unix, but
now also running under DOS, Amiga, and other operating systems. By "TeX
implementation", we mean all of the standard programs developed by the
Stanford TeX project directed by Donald E. Knuth: Metafont, DVItype,
GFtoDVI, BibTeX, Tangle, etc., as well as TeX itself. Other programs
are also included: DVIcopy, written by Peter Breitenlohner, MetaPost
and its utilities (derived from Metafont), by John Hobby, etc.

  General strategy: Web2c works, as its name implies, by translating the
WEB source in which TeX is written into C source code. Its output is
not self-contained, however; it makes extensive use of many macros and
functions in a library (the `web2c/lib' directory in the sources).
Therefore, it will not work without change on an arbitrary WEB program.

  Availability: All of Web2c is freely available--"free" both in the
sense of no cost (free ice cream) and of having the source code to
modify and/or redistribute (free speech).  (see unixtex.ftp (kpathsea).
ftp, for the practical details of how to obtain
Web2c.)  Different parts of the Web2c distribution have different
licensing terms, however, reflecting the different circumstances of
their creation; consult each source file for exact details.  The main
practical implication for redistributors of Web2c is that the
executables are covered by the GNU Public License, and therefore anyone
who gets a binary distribution must also get the sources, as explained
by the terms of the GPL (see Copying (kpathsea)). The GPL
covers the Web2c executables, including `tex', because the Free
Software Foundation sponsored the initial development of the Kpathsea
library that Web2c uses.  The basic source files from Stanford, however,
have their own copyright terms or are in the public domain, and are not
covered by the GPL.

  History: Tomas Rokicki originated the TeX-to-C system in 1987,
working from the first change files for TeX under Unix, which were done
primarily by Howard Trickey and Pavel Curtis. Tim Morgan then took over
development and maintenance for a number of years; the name changed to
Web-to-C somewhere in there.  In 1990, Karl Berry became the
maintainer.  He made many changes to the original sources, and started
using the shorter name Web2c.  In 1997, Olaf Weber took over.  Dozens of
other people have contributed; their names are listed in the
`ChangeLog' files.

  Other acknowledgements: The University of Massachusetts at Boston
(particularly Rick Martin and Bob Morris) has provided computers and ftp
access to me for many years.  Richard Stallman at the Free Software
Foundation employed me while I wrote the original path searching library
(for the GNU font utilities).  (rms also gave us Emacs, GDB, and GCC,
without which I cannot imagine developing Web2c.)  And, of course, TeX
would not exist in the first place without Donald E. Knuth.

  Further reading: References.

Installation
************

  (A copy of this chapter is in the distribution file `web2c/INSTALL'.)

  Installing Web2c is mostly the same as installing any other
Kpathsea-using program.  Therefore, for the basic steps involved, see
Installation (kpathsea).  (A copy is in the file
`kpathsea/INSTALL'.)

  One peculiarity to Web2c is that the source distribution comes in two
files: `web.tar.gz' and `web2c.tar.gz'.  You must retrieve and unpack
them both.  (We have two because the former archive contains the very
large and seldom-changing original WEB source files.)  See
unixtex.ftp (kpathsea).ftp.

  Another peculiarity is the MetaPost program.  Although it has been
installed previously as `mp', as of Web2c 7.0 the installed name is now
`mpost', to avoid conflict with the `mp' program that does
prettyprinting.  This approach was recommended by the MetaPost author,
John Hobby.  If you as the TeX administrator wish to make it available
under its shorter name as well, you will have to set up a link or some
such yourself.  And of course individual users can do the same.

  For solutions to common installation problems and information on how
to report a bug, see the file `kpathsea/BUGS' (see Bugs (kpathsea)).
See also the Web2c home page,
`http://www.tug.org/web2c'.

  Points worth repeating:

   * Before starting the standard compilation and installation you must
     install the basic fonts, macros, and other library files.  See
     Installation (kpathsea).

   * If you do not wish to use the standard file locations, see
     Changing search paths (kpathsea).

   * Some Web2c features are enabled or disabled at `configure' time,
     as described in the first section below.

`configure' options
===================

  This section gives pointers to descriptions of the `--with' and
`--enable' `configure' arguments that Web2c accepts.  Some are specific
to Web2c, others are generic to all Kpathsea-using programs.

  For a list of all the options `configure' accepts, run `configure
--help'.  The generic options are listed first, and the
package-specific options come last.

  For a description of the generic options (which mainly allow you to
specify installation directories) and basic `configure' usage, see
Running `configure' scripts (autoconf), a copy
is in the file `kpathsea/CONFIGURE'.

`--disable-dump-share'
     Do not make fmt/base/mem files sharable across different endian
     architectures.  See Hardware and memory dumps.

`--without-maketexmf-default'
`--without-maketexpk-default'
`--without-maketextfm-default'
`--with-maketextex-default'
     Enable or disable the dynamic generation programs.  See mktex configuration (kpathsea).
     The defaults are
     the inverse of the options, i.e., everything is enabled except
     `mktextex'.

`--enable-auto-core'
     Dump `core' if the input file is
     `HackyInputFileNameForCoreDump.tex'.  See Preloaded executables.

`--enable-shared'
     Build Kpathsea as a shared library.  See Shared library (kpathsea).

`--with-editor=CMD'
     Change the default editor invoked by the `e' interactive command.
     See Editor invocation.

`--with-epsfwin'
`--with-hp2627win'
`--with-mftalkwin'
`--with-nextwin'
`--with-regiswin'
`--with-suntoolswin'
`--with-tektronixwin'
`--with-unitermwin'
`--with-x'
`--with-x-toolkit=KIT'
`--with-x11win'
`--with-x11'
     Define Metafont graphics support; by default, no graphics support
     is enabled.  See Online Metafont graphics.

`--x-includes=DIR'
`--x-libraries=DIR'
     Define the locations of the X11 include files and libraries; by
     default, `configure' does its best to guess).  See Optional Features (autoconf).
     A copy is in
     `kpathsea/CONFIGURE'.

Compile-time options
====================

  In addition to the `configure' options listed in the previous
section, there are a few things that can be affected at compile-time
with C definitions, rather than with `configure'.  Using any of these
is unusual.

  To specify extra compiler flags (`-DNAME' in this case), the simplest
thing to do is:
     make XCFLAGS="CCOPTIONS"
   You can also set the `CFLAGS' environment variable before running
`configure'.  See configure environment (kpathsea).

Anyway, here are the possibilities:

`-DFIXPT'
`-DNO_MF_ASM'
     Use the original WEB fixed-point routines for Metafont and MetaPost
     arithmetic calculations regarding fractions.  By default,
     assembly-language routines are used on x86 hardware with GNU C
     (unless `NO_MF_ASM' is defined), and floating-point routines are
     used otherwise.

`-DIPC_DEBUG'
     Report on various interprocess communication activities.  See
     IPC and TeX.

Additional targets
==================

  Web2c has several Make targets besides the standard ones.  You can
invoke these either in the top level directory of the source
distribution (the one containing `kpathsea/' and `web2c/'), or in the
`web2c/' directory.

`c-sources'
     Make only the C files, translated from the Web sources, presumably
     because you want to take them to a non-Unix machine.

`formats'
`install-formats'
     Make or install all the memory dumps (see Memory dumps.).  By
     default, the standard plain formats plus `latex.fmt' are made.  You
     can add other formats by redefining the `fmts', `bases', and
     `mems' variables.  See the top of `web2c/Makefile' for the
     possibilities.

`fmts'
`install-fmts'
     Make or install the TeX `.fmt' files. See initex invocation.

`bases'
`install-bases'
     Make or install the Metafont `.base' files.  See inimf invocation.

`mems'
`install-mems'
     Make or install the MetaPost `.mem' files.  See inimpost invocation.

`triptrap'
`trip'
`trap'
`mptrap'
     To run the torture tests for TeX, Metafont, and MetaPost
     (respectively).  See the next section.

Trip, trap, and mptrap: Torture tests
=====================================

  To validate your TeX, Metafont, and MetaPost executables, run `make
triptrap'.  This runs the trip, trap, and mptrap "torture tests".  See
the files `triptrap/tripman.tex', `triptrap/trapman.tex', and
`triptrap/mptrap.readme' for detailed information and background on the
tests.

  The differences between your executables' behavior and the standard
values will show up on your terminal.  The usual differences (these are
all acceptable) are:

   * string usage and table sizes;

   * glue set ratios;

   * `down4', `right4', and `y4' commands in DVItype output;

   * dates and times.

Any other differences are trouble. The most common culprit in the past
has been compiler bugs, especially when optimizing.  See TeX or Metafont failing (kpathsea).

  The files `trip.diffs', `mftrap.diffs', and `mptrap.diffs' in the
`triptrap' directory show the standard diffs against the original
output.  If you diff your diffs against these files, you should come up
clean.  For example
     make trip >&mytrip.diffs
     diff triptrap/trip.diffs mytrip.diffs

  To run the tests separately, use the targets `trip', `trap', and
`mptrap'.

  To run simple tests for all the programs as well as the torture tests,
run `make check'.  You can compare the output to the distributed file
`tests/check.log' if you like.

Runtime options
===============

  Besides the configure- and compile-time options described in the
previous sections, you can control a number of parameters (in
particular, array sizes) in the `texmf.cnf' runtime file read by
Kpathsea (see Config files (kpathsea)).

  Rather than exhaustively listing them here, please see the last
section of the distributed `kpathsea/texmf.cnf'.  Some of the more
interesting values:

`main_memory'
     Total words of memory available, for TeX, Metafont, and MetaPost.
     Must remake the format file after changing.

`extra_mem_bot'
     Extra space for "large" TeX data structures: boxes, glue,
     breakpoints, et al.  If you use PiCTeX, you may well want to set
     this.

`font_mem_size'
     Words of font info available for TeX; this is approximately the
     total size of all TFM files read.

`hash_extra'
     Additional space for the hash table of control sequence names.
     Approximately 10,000 control sequences can be stored in the main
     hash table; if you have a large book with numerous
     cross-references, this might not be enough, and thus you will want
     to set `hash_extra'.

  Of course, ideally all arrays would be dynamically expanded as
necessary, so the only limiting factor would be the amount of swap space
available.  Unfortunately, implementing this is extremely difficult, as
the fixed size of arrays is assumed in many places throughout the source
code.  These runtime limits are a practical compromise between the
compile-time limits in previous versions, and truly dynamic arrays.  (On
the other hand, the Web2c BibTeX implementation does do dynamic
reallocation of some arrays.)

Commonalities
*************

  Many aspects of the TeX system are the same among more than one
program, so we describe all those pieces together, here.

Option conventions
==================

  To provide a clean and consistent behavior, we chose to have all these
programs use the GNU function `getopt_long_only' to parse command lines.

  As a result, you can:
   * give the options in any order, interspersed as you wish with
     non-option arguments;

   * use `-' or `--' to start an option name;

   * use any unambiguous abbreviation for an option name;

   * separate option names and values with either `=' or one or more
     spaces;

   * use filenames that would otherwise look like options by putting
     them after an option `--'.

  By convention, non-option arguments, if specified, generally define
the name of an input file, as documented for each program.

  If a particular option with a value is given more than once, it is the
last value that counts.

  For example, the following command line specifies the options `foo',
`bar', and `verbose'; gives the value `baz' to the `abc' option, and
the value `xyz' to the `quux' option; and specifies the filename
`-myfile-'.

     -foo --bar -verb -abc=baz -quux karl --quux xyz -- -myfile-

Common options
==============

  All of these programs accept the standard GNU `--help' and
`--version' options, and several programs accept `--verbose'.  Rather
than writing identical descriptions in every node, they are described
here.

`--help'
     Print a usage message listing basic usage and all available
     options to standard output, then exit successfully.

`--verbose'
     Print progress reports to standard output.

`--version'
     Print the version number to standard output, then exit
     successfully.

  TeX, Metafont, and MetaPost have additional options in common:

`-kpathsea-debug=NUMBER'
     Set path searching debugging flags according to the bits of NUMBER
     (see Debugging (kpathsea)).  You can also specify
     this in `KPATHSEA_DEBUG' environment variable (for all Web2c
     programs).  (The command line value overrides.)  The most useful
     value is `-1', to get all available output.

`-ini'
     Enable the "initial" form of the program (see Initial and virgin.).
     This is implicitly set if the program name is `initex'
     resp. `inimf' resp. `inimpost'.

`-interaction=STRING'
     Set the interaction mode from the command line.  The STRING must
     be one of `batchmode', `nonstopmode', `scrollmode', or
     `errorstopmode'.

`-fmt=DUMPNAME'
`-base=DUMPNAME'
`-mem=DUMPNAME'
     Use DUMPNAME instead of the program name or a `%&' line to
     determine the name of the memory dump file read (`fmt' for TeX,
     `base' for Metafont, `mem' for MetaPost).  See Memory dumps.
     Also sets the program name to DUMPNAME if no `-progname' option
     was given.  When creating a dump, this option will also set the
     name of the dump file.

`-progname=STRING'
     Set program (and memory dump) name to STRING.  This may affect the
     search paths and other values used (see Config files (kpathsea)).
     Using this option is equivalent to
     making a link named STRING to the binary and then invoking the
     binary under that name.  See Memory dumps.

`-translate-file=TCXFILE'
     Use TCXFILE to define which characters are printable and
     translations between the internal and external character sets.
     Moreover, TCXFILE can be explicitly declared in  the first line of
     the main input file `%& -translate-file=TCXFILE'.  This is the
     recommended method for portability reasons.  See TCX files.

Path searching
==============

  All of the Web2c programs, including TeX, which do path searching use
the Kpathsea routines to do so.  The precise names of the environment
and configuration file variables which get searched for particular file
formatted are therefore documented in the Kpathsea manual (see
Supported file formats (kpathsea)).  Reading
`texmf.cnf' (see Config files (kpathsea)), invoking
`mktex...' scripts (see mktex scripts (kpathsea)), and
so on are all handled by Kpathsea.

  The programs which read fonts make use of another Kpathsea feature:
`texfonts.map', which allows arbitrary aliases for the actual names of
font files; for example, `Times-Roman' for `ptmr8r.tfm'.  The
distributed (and installed by default) `texfonts.map' includes aliases
for many widely available PostScript fonts by their PostScript names.

Output file location
====================

  All the programs generally follow the usual convention for output
files.  Namely, they are placed in the directory current when the
program is run, regardless of any input file location; or, in a few
cases, output is to standard output.

  For example, if you run `tex /tmp/foo', for example, the output will
be in `./foo.dvi' and `./foo.log', not `/tmp/foo.dvi' and
`/tmp/foo.log'.

  However, if the current directory is not writable, the main programs
(TeX, Metafont, MetaPost, and BibTeX) make an exception: if the
environment variable or config file value `TEXMFOUTPUT' is set (it is
not by default), output files are written to the directory specified.
This is useful when you are in some read-only distribution directory,
perhaps on a CD-ROM, and want to TeX some documentation, for example.

Three programs: Metafont, MetaPost, and TeX
===========================================

  TeX, Metafont, and MetaPost have a number of features in common.
Besides the ones here, the common command-line options are described in
the previous section.  The configuration file options that let you
control some array sizes and other features are described in
Runtime options.

Initial and virgin
------------------

  The TeX, Metafont, and MetaPost programs each have two main variants,
called initial and virgin.  As of Web2c 7, one executable suffices for
both variants.

  The initial form is enabled if:
  1. the `-ini' option was specified; or

  2. the program name is `initex' resp. `inimf' resp.  `inimpost'; or

  3. the first line of the main input file is `%&ini';

otherwise, the virgin form is used.

  The "virgin" form is the one generally invoked for production use.
The first thing it does is read a memory dump (see Determining the memory dump to use.),
and then proceeds on with the main job.

  The "initial" form is generally used only to create memory dumps (see
the next section).  It starts up more slowly than the virgin form,
because it must do lengthy initializations that are encapsulated in the
memory dump file.

  In the past, there was a third form, "preloaded" executables.  This
is no longer recommended or widely used; but see the section below if
you're interested anyway.  In this case, the memory dump file was read
in to the virgin form, a core dump of the running executable was done,
and the `undump' program run to create a new binary.  Nowadays, reading
memory dumps is fast enough that this is generally no longer worth the
cost in disk space and unshared executables.

Preloaded executables
.....................

  Specifying `--enable-auto-core' to `configure' tells TeX, Metafont,
and MetaPost to suicide with a `SIGQUIT' on an input filename of
`HackyInputFileNameForCoreDump.tex' (all three programs use the `.tex'
suffix). This produces a memory dump of the running executable in a
file `core'.  (This is unrelated to the standard memory dump feature in
these programs; see Memory dumps.).

  You don't actually need to do this to produce a core dump.  Just
typing your quit character (usually <CTRL-\>) when the program is
waiting for input (at `**') will have the same result.  But a few sites
want to reliably generate a core dump without human intervention; that's
what `--enable-auto-core' is for.

  With the program `undump', you can use `core' to reconstitute a
"preloaded" executable, which does not need to read a `.fmt' file to
get started.  Although preloaded executables save startup time, they
have a big disadvantage: neither the disk space to store them nor their
code segments (at runtime) can be shared.  Therefore, if both `tex' and
`latex' are running, twice as much memory will be consumed, to the
general detriment of performance.

  The `undump' program is not part of the Web2c distribution, but you
can get it from the CTAN archives as `CTAN:/support/undump', and it is
included in several TeX distributions (see unixtex.ftp (kpathsea).
ftp.).

Memory dumps
------------

  In typical use, TeX, Metafont, and MetaPost require a large number of
macros to be predefined; therefore, they support "memory dump" files,
which can be read much more efficiently than ordinary source code.

Creating memory dumps
.....................

  The programs all create memory dumps in slightly idiosyncratic
(thought substantially similar) way, so we describe the details in
separate sections (references below).  The basic idea is to run the
initial version of the program (see Initial and virgin.), read the
source file to define the macros, and then execute the `\dump'
primitive.

  Also, each program uses a different filename extension for its memory
dumps, since although they are completely analogous they are not
interchangeable (TeX cannot read a Metafont memory dump, for example).

  Here is a list of filename extensions with references to examples of
creating memory dumps:

TeX
     (`.fmt') initex invocation.

Metafont
     (`.base') inimf invocation.

MetaPost
     (`.mem') inimpost invocation.

  When making memory dumps, the programs read environment variables and
configuration files for path searching and other values as usual.  If
you are making a new installation and have environment variables
pointing to an old one, for example, you will probably run into
difficulties.

Determining the memory dump to use
..................................

  The virgin form (see Initial and virgin.) of each program always
reads a memory dump before processing normal source input.  All three
programs determine the memory dump to use in the same way:

  1. If the first non-option command-line argument begins with `&', the
     program uses the remainder of that argument as the memory dump
     name.  For example, running `tex \&super' reads `super.fmt'.  (The
     backslash protects the `&' against interpretation by the shell.)

  2. If the `-fmt' resp. `-base' resp. `-mem' option is specified, its
     value is used.

  3. If the `-progname' option is specified, its value is used.

  4. If the first line of the main input file (which must be specified
     on the command line, not in response to `**') is `%&DUMP', and
     DUMP is an existing memory dump of the appropriate type, DUMP is
     used.

     The first line of the main input file can also specify which
     character translation file is to be used:
     `%&-translate-file=TCXFILE' (see TCX files.).

     These two roles can be combined: `%&DUMP -translate-file=TCXFILE'.
     If this is done, the name of the dump must be given first.

  5. Otherwise, the program uses the program invocation name, most
     commonly `tex' resp. `mf' resp. `mpost'.  For example, if `latex'
     is a link to `tex', and the user runs `latex foo', `latex.fmt'
     will be used.

Hardware and memory dumps
.........................

  By default, memory dump files are generally sharable between
architectures of different types; specifically, on machines of different
endianness (see Byte order (libc)).  (This is a feature
of the Web2c implementation, and is not true of all TeX
implementations.)  If you specify `--disable-dump-share' to
`configure', however, memory dumps will be endian-dependent.

  The reason to do this is speed.  To achieve endian-independence, the
reading of memory dumps on LittleEndian architectures, such as PC's and
DEC architectures, is somewhat slowed (all the multibyte values have to
be swapped).  Usually, this is not noticeable, and the advantage of
being able to share memory dumps across all platforms at a site far
outweighs the speed loss.  But if you're installing Web2c for use on
LittleEndian machines only, perhaps on a PC being used only by you, you
may wish to get maximum speed.

  TeXnically, even without `--disable-dump-share', sharing of `.fmt'
files cannot be guaranteed to work.  Floating-point values are always
written in native format, and hence will generally not be readable
across platforms.  Fortunately, TeX uses floating point only to
represent glue ratios, and all common formats (plain, LaTeX, AMSTeX,
...) do not do any glue setting at `.fmt'-creation time.  Metafont and
MetaPost do not use floating point in any dumped value at all.

  Incidentally, different memory dump files will never compare equal
byte-for-byte, because the program always dumps the current date and
time. So don't be alarmed by just a few bytes difference.

  If you don't know what endianness your machine is, and you're curious,
here is a little C program to tell you. (The `configure' script
contains a similar program.)  This is from the book `C: A Reference
Manual', by Samuel P. Harbison and Guy L. Steele Jr. (see
References.).

     main ()
     {
       /* Are we little or big endian?  From Harbison&Steele.  */
       union
       {
         long l;
         char c[sizeof (long)];
       } u;
       u.l = 1;
       if (u.c[0] == 1)
         printf ("LittleEndian\n");
       else if (u.c[sizeof (long) - 1] == 1)
         printf ("BigEndian\n");
       else
         printf ("unknownEndian");

       exit (u.c[sizeof (long) - 1] == 1);
     }

Editor invocation
-----------------

  TeX, Metafont, and MetaPost all (by default) stop and ask for user
intervention at an error.  If the user responds with `e' or `E', the
program invokes an editor.

  Specifying `--with-editor=CMD' to `configure' sets the default editor
command string to CMD.  The environment variables/configuration values
`TEXEDIT', `MFEDIT', and `MPEDIT' (respectively) override this.  If
`--with-editor' is not specified, the default is `vi +%d %s'.

  In this string, `%d' is replaced by the line number of the error, and
`%s' is replaced by the name of the current input file.

`\input' filenames
------------------

  TeX, Metafont, and MetaPost source programs can all read other source
files with the `\input' (TeX) and `input' (MF and MP) primitives:
     \input NAME % in TeX

  The file NAME can always be terminated with whitespace; for Metafont
and MetaPost, the statement terminator `;' also works.  (LaTeX and
other macro packages provide other interfaces to `\input' that allow
different notation; here we are concerned only with the primitive
operation.)  This means that `\input' filenames cannot directly contain
whitespace, even though Unix has no trouble.  Sorry.

  On the other hand, various C library routines and Unix itself use the
null byte (character code zero, ASCII NUL) to terminate strings.  So
filenames in Web2c cannot contain nulls, even though TeX itself does
not treat NUL specially.

  Furthermore, some older Unix variants do not allow eight-bit
characters (codes 128-255) in filenames.

  For maximal portability of your document across systems, use only the
characters `a'-`z', `0'-`9', and `.', and restrict your filenames to at
most eight characters (not including the extension), and at most a
three-character extension.  Do not use anything but simple filenames,
since directory separators vary among systems; instead, add the
necessary directories to the appropriate search path.

  Finally, the present Web2c implementation does `~' and `$' expansion
on NAME, unlike Knuth's original implementation and older versions of
Web2c.  Thus:
     \input ~jsmith/$foo.bar
  will dereference the environment variable or Kpathsea config file
value `foo' and read that file extended with `.bar' in user `jsmith''s
home directory.  (You can also use braces, as in `${foo}bar' if you
want to follow the variable name with a letter, numeral, or `_'.)

  (So you could define an environment variable value including
whitespace and get the program to read such a filename that way, if you
need to.)

  In all the common TeX formats (plain TeX, LaTeX, AMSTeX), the
characters `~' and `~' have special category codes, so to actually use
these in a document you have to change their catcodes or use `\string'.
(The result is unportable anyway, see the suggestions above.)  The
place where they are most likely to be useful is when typing
interactively.

TeX: Typesetting
****************

  TeX is a typesetting system: it was especially designed to handle
complex mathematics, as well as most ordinary text typesetting.

  TeX is a batch language, like C or Pascal, and not an interactive
"word processor": you compile a TeX input file into a corresponding
device-independent (DVI) file (and then translate the DVI file to the
commands for a particular output device).  This approach has both
considerable disadvantages and considerable advantages.  For a complete
description of the TeX language, see `The TeXbook' (see
References.).  Many other books on TeX, introductory and otherwise,
are available.

`tex' invocation
================

  TeX (usually invoked as `tex') formats the given text and commands,
and outputs a corresponding device-independent representation of the
typeset document.  This section merely describes the options available
in the Web2c implementation.  For a complete description of the TeX
typesetting language, see `The TeXbook' (see References.).

  TeX, Metafont, and MetaPost process the command line (described here)
and determine their memory dump (fmt) file in the same way (see
Memory dumps.).  Synopses:

     tex [OPTION]... [TEXNAME[.tex]] [TEX-COMMANDS]
     tex [OPTION]... \FIRST-LINE
     tex [OPTION]... &FMT ARGS

  TeX searches the usual places for the main input file TEXNAME (see
Supported file formats (kpathsea)), extending
TEXNAME with `.tex' if necessary.  To see all the relevant paths, set
the environment variable `KPATHSEA_DEBUG' to `-1' before running the
program.

  After TEXNAME is read, TeX processes any remaining TEX-COMMANDS on
the command line as regular TeX input.  Also, if the first non-option
argument begins with a TeX escape character (usually `\'), TeX
processes all non-option command-line arguments as a line of regular
TeX input.

  If no arguments or options are specified, TeX prompts for an input
file name with `**'.

  TeX writes the main DVI output to the file `BASETEXNAME.dvi', where
BASETEXNAME is the basename of TEXNAME, or `texput' if no input file
was specified.  A DVI file is a device-independent binary
representation of your TeX document.  The idea is that after running
TeX, you translate the DVI file using a separate program to the
commands for a particular output device, such as a PostScript printer
(see Introduction (dvipsk)) or an X Window System display (see
xdvi(1)).

  TeX also reads TFM files for any fonts you load in your document with
the `\font' primitive.  By default, it runs an external program named
`mktextfm' to create any nonexistent TFM files.  You can disable this
at configure-time or runtime (see mktex configuration (kpathsea)).
This is enabled mostly for the sake
of the EC fonts, which can be generated at any size.

  TeX can write output files, via the `\openout' primitive; this opens
a security hole vulnerable to Trojan horse attack: an unwitting user
could run a TeX program that overwrites, say, `~/.rhosts'.  (MetaPost
has a `write' primitive with similar implications).  To alleviate this,
there is a configuration variable `openout_any', which selects one of
three levels of security.  When it is set to `a' (for "any"), no
restrictions are imposed.  When it is set to `r' (for "restricted"),
filenames beginning with `.' are disallowed (except `.tex' because
LaTeX needs it).  When it is set to `p' (for "paranoid") additional
restrictions are imposed: an absolute filename must refer to a file in
(a subdirectory) of `TEXMFOUTPUT', and any attempt to go up a directory
level is forbidden (that is, paths may not contain a `..'  component).
The paranoid setting is the default.  (For backwards compatibility, `y'
and `1' are synonyms of `a', while `n' and `0' are synonyms for `r'.)

  In any case, all `\openout' filenames are recorded in the log file,
except those opened on the first line of input, which is processed when
the log file has not yet been opened.  (If you as a TeX administrator
wish to implement more stringent rules on `\openout', modifying the
function `openoutnameok' in `web2c/lib/texmfmp.c' is intended to
suffice.)

  The program accepts the following options, as well as the standard
`-help' and `-version' (see Common options.):
`-kpathsea-debug=NUMBER'
`-ini'
`-fmt=FMTNAME'
`-progname=STRING'
`-translate-file=TCXFILE'
     These options are common to TeX, Metafont, and MetaPost.  See
     Common options.

`-ipc'
`-ipc-start'
     With either option, TeX writes its DVI output to a socket as well
     as to the usual `.dvi' file.  With `-ipc-start', TeX also opens a
     server program at the other end to read the output.  See IPC and TeX.

     These options are available only if the `--enable-ipc' option was
     specified to `configure' during installation of Web2c.

`-mktex=FILETYPE'
`-no-mktex=FILETYPE'
     Turn on or off the `mktex' script associated with FILETYPE.  The
     only values that make sense for FILETYPE are `tex' and `tfm',

`-mltex'
     If `INITEX' (see Initial and virgin.), enable MLTeX extensions
     such as `\charsubdef'.  Implicitly set if the program name is
     `mltex'.  See MLTeX.

`-output-comment=STRING'
     Use STRING as the DVI file comment.  Ordinarily, this comment
     records the date and time of the TeX run, but if you are doing
     regression testing, you may not want the DVI file to have this
     spurious difference.  This is also taken from the environment
     variable and config file value `output_comment'.

`-shell-escape'
     Enable the `\write18{SHELL-COMMAND}' feature.  This is also
     enabled if the environment variable or config file value
     `shell_escape' is set to `t'.  (For backwards compatibility, `y'
     and `1' are accepted as synonyms of `t').  It is disabled by
     default to avoid security problems.  When enabled, the
     SHELL-COMMAND string (which first undergoes the usual TeX
     expansions, just as in `\special') is passed to the command shell
     (via the C library function `system').  The output of
     SHELL-COMMAND is not diverted anywhere, so it will not appear in
     the log file.  The system call either happens at `\output' time or
     right away, according to the absence or presence of the
     `\immediate' prefix, as usual for `\write'.  (If you as a TeX
     administrator wish to implement more stringent rules on what can
     be executed, you will need to modify `tex.ch'.)

`initex' invocation
===================

  `initex' is the "initial" form of TeX, which does lengthy
initializations avoided by the "virgin" (`vir') form, so as to be
capable of dumping `.fmt' files (see Memory dumps.).  For a
detailed comparison of virgin and initial forms, see Initial and virgin..

  For a list of options and other information, see tex invocation..

  Unlike Metafont and MetaPost, many format files are commonly used with
TeX.  The standard one implementing the features described in the
`TeXbook' is `plain.fmt', also known as `tex.fmt' (again, see Memory dumps.).
It is created by default during installation, but you can
also do so by hand if necessary (e.g., if an update to `plain.tex' is
issued):
     initex '\input plain \dump'

(The quotes prevent interpretation of the backslashes from the shell.)
Then install the resulting `plain.fmt' in `$(fmtdir)'
(`/usr/local/share/texmf/web2c' by default), and link `tex.fmt' to it.

  The necessary invocation for generating a format file differs for each
format, so instructions that come with the format should explain.  The
top-level `web2c' Makefile has targets for making most common formats:
plain latex amstex texinfo eplain.  See Formats, for more details
on TeX formats.

`virtex' invocation
===================

  `virtex' is the "virgin" form of TeX, which avoids the lengthy
initializations done by the "initial" (`ini') form, and is thus what is
generally used for production work.  For a detailed comparison of
virgin and initial forms, see Initial and virgin..

  For a list of options and other information, see tex invocation.

Formats
=======

  TeX "formats" are large collections of macros, possibly dumped into a
`.fmt' file (see Memory dumps.) by `initex' (see initex invocation.).
A number of formats are in reasonably widespread use,
and the Web2c Makefile has targets to make the versions current at the
time of release.  You can change which formats are automatically built
by setting the `fmts' Make variable; by default, only the `plain' and
`latex' formats are made.

  You can get the latest versions of most of these formats from the CTAN
archives in subdirectories of `CTAN:/macros' (for CTAN info, see
unixtex.ftp (kpathsea).ftp.).  The archive
`ftp://ftp.tug.org/tex/lib.tar.gz' (also available from CTAN) contains
most of these formats (although perhaps not the absolute latest
version), among other things.

latex
     The most widely used format.  The current release is named `LaTeX
     2e'; new versions are released approximately every six months, with
     patches issued as needed.  The old release was called `LaTeX 2.09',
     and is no longer maintained or supported.  LaTeX attempts to
     provide generic markup instructions, such as "emphasize", instead
     of specific typesetting instructions, such as "use the 10pt
     Computer Modern italic font".

amstex
     The official typesetting system of the American Mathematical
     Society, used to produce nearly all of its publications, e.g.,
     `Mathematical Reviews'.  Like LaTeX, it encourages generic markup
     commands.  The AMS also provides a LaTeX package for authors who
     prefer LaTeX (see the `amslatex' item below).

texinfo
     The documentation system developed and maintained by the Free
     Software Foundation for their software manuals.  It can be
     automatically converted into plain text, a machine-readable
     on-line format called `info', HTML, etc.

eplain
     The "expanded plain" format provides various common features (e.g.,
     symbolic cross-referencing, tables of contents, indexing, citations
     using BibTeX), for those authors who prefer to handle their own
     high-level formatting.

lamstex
     Augments AMSTeX with LaTeX-like features.

amslatex
     An LaTeX package (see `latex' item above), that augments LaTeX
     with AMSTeX-like features.

slitex
     An obsolete LaTeX 2.09 format for making slides.  It is replaced by
     the `slides' document class.

Languages and hyphenation
=========================

  TeX supports most natural languages.  See also TeX extensions.

MLTeX: Multi-lingual TeX
------------------------

  Multi-lingual TeX (`mltex') is an extension of TeX originally written
by Michael Ferguson and now updated and maintained by Bernd Raichle.
It allows the use of non-existing glyphs in a font by declaring glyph
substitutions.  These are restricted to substitutions of an accented
character glyph, which need not be defined in the current font, by its
appropriate `\accent' construction using a base and accent character
glyph, which do have to exist in the current font.  This substitution
is automatically done behind the scenes, if necessary, and thus MLTeX
additionally supports hyphenation of words containing an accented
character glyph for fonts missing this glyph (e.g., Computer Modern).
Standard TeX suppresses hyphenation in this case.

  MLTeX works at `.fmt'-creation time: the basic idea is to specify the
`-mltex' option to TeX when you `\dump' a format.  Then, when you
subsequently invoke TeX and read that `.fmt' file, the MLTeX features
described below will be enabled.

  Generally, you use special macro files to create an MLTeX `.fmt'
file.  See:
     CTAN:/systems/generic/mltex
     `ftp://ftp.univ-rennes1.fr/pub/GUTenberg/french/'

  The sections below describe the two new primitives that MLTeX defines.
Aside from these, MLTeX is completely compatible with standard TeX.

`\charsubdef': Character substitutions
......................................

  The most important primitive MLTeX adds is `\charsubdef', used in a
way reminiscent of `\chardef':
     \charsubdef COMPOSITE [=] ACCENT BASE

  Each of COMPOSITE, ACCENT, and BASE are font glyph numbers, expressed
in the usual TeX syntax: `\e symbolically, '145 for octal, "65 for hex,
101 for decimal.

  MLTeX's `\charsubdef' declares how to construct an accented character
glyph (not necessarily existing in the current font) using two
character glyphs (that do exist).  Thus it defines whether a character
glyph code, either typed as a single character or using the `\char'
primitive, will be mapped to a font glyph or to an `\accent' glyph
construction.

  For example, if you assume glyph code 138 (decimal) for an
e-circumflex and you are using the Computer Modern fonts, which have
the circumflex accent in position 18 and lowercase `e' in the usual
ASCII position 101 decimal, you would use `\charsubdef' as follows:

     \charsubdef 138 = 18 101

  For the plain TeX format to make use of this substitution, you have
to redefine the circumflex accent macro `\^' in such a way that if its
argument is character `e' the expansion `\char138 ' is used instead of
`\accent18 e'.  Similar `\charsubdef' declaration and macro
redefinitions have to be done for all other accented characters.

  To disable a previous `\charsubdef C', redefine C as a pair of zeros.
For example:
     \charsubdef '321 = 0 0  % disable N tilde

(Octal '321 is the ISO Latin-1 value for the Spanish N tilde.)

  `\charsubdef' commands should only be given once.  Although in
principle you can use `\charsubdef' at any time, the result is
unspecified.  If `\charsubdef' declarations are changed, usually either
incorrect character dimensions will be used or MLTeX will output
missing character warnings.  (The substitution of a `\charsubdef' is
used by TeX when appending the character node to the current horizontal
list, to compute the width of a horizontal box when the box gets
packed, and when building the `\accent' construction at
`\shipout'-time.  In summary, the substitution is accessed often, so
changing it is not desirable, nor generally useful.)

`\tracingcharsubdef': Substitution diagnostics
..............................................

  To help diagnose problems with `\charsubdef', MLTeX provides a new
primitive parameter, `\tracingcharsubdef'.  If positive, every use of
`\charsubdef' will be reported.  This can help track down when a
character is redefined.

  In addition, if the TeX parameter `\tracinglostchars' is 100 or more,
the character substitutions actually performed at `\shipout'-time will
be recorded.